home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu696.dms / pu696.adf / XPR_Libs / xprbplus.doc < prev    next >
Text File  |  1993-02-13  |  12KB  |  331 lines
  1.                 Documentation for XPRBPlus.library
  2.                 ==================================
  3.  
  4.                     Version 1.1 - 8th June 1992
  5.                     ===========================
  6.  
  7.               by Terence (Terry) Finney [100021,2621]
  8.               =======================================
  9.  
  10.  
  11. 1. Introduction
  12. ===============
  13.  
  14. XPRBPlus.library is an Amiga shared library for use with Terminal
  15. programs which support the XPR standard, such as Term, VLT and
  16. Backtalk.
  17.  
  18. Its purpose is to provide the improved facilities allowed by the
  19. Compuserve B Plus Protocol. This release implements the 'File
  20. Information' facility which enables file sizes and hence estimated
  21. download times to be displayed during downloads and 'Download
  22. Resume' which allows partial file transfers to be completed after
  23. an abort.
  24.  
  25.  
  26. 2. Disclaimer
  27. =============
  28.  
  29. This is my first serious programming effort, so I stress that the
  30. usual disclaimers apply. I am not a programmer by profession. My
  31. intention in producing this library was to give myself a challenge
  32. and hopefully end up with something offering the enhancements of
  33. other XPR libraries such as XPRZmodem. If after attempting to
  34. download a 200k file at 300 Baud you find that an error has
  35. occurred rendering the file useless, please hold your breath, count
  36. to ten, read this section again and see the Section 12 at the end
  37. of this document for details of how to report bugs.
  38.  
  39.  
  40. 3. Credits
  41. ==========
  42.  
  43. The protocol support code for this library was supplied by
  44. Compuserve in the bpcsrc.arc archive and is by various authors.
  45. This archive also contains essential information on implementing
  46. the protocol. Other information was obtained from 'The Compuserve B
  47. Plus Protocol' by Russ Ranshaw (available as bplus.arc) and
  48. 'B/Quick B Protocol Information' by Steve Sneed (available as
  49. proto.nfo).
  50.  
  51. This exercise would have been impossible without reference to the
  52. source code for XPRZmodem.library originally written by Rick
  53. Huebner and revised by William M. Perkins, to XPRQuickb.library
  54. from The Software Distillery, and to the example XPRAscii.library
  55. by Willy Langeveld.
  56.  
  57. Further credit is of course due to Willy Langeveld for creating the
  58. XPR specification in the first place.
  59.  
  60. The library was written in Lattice (SAS) C.
  61.  
  62. Thanks also to Steve Ahlstrom for his comments and example source
  63. code.
  64.  
  65. Last but not least, special thanks are due to Vic Reeves, whose 'I
  66. Will Cure You' album was echoing around the room the first time a
  67. download was achieved successfully. Definitely the best debugging
  68. tool ever invented.
  69.  
  70.  
  71. 4. Installation
  72. ===============
  73.  
  74. First, copy the XPRBPlus.library to LIBS: Then enter your XPR
  75. supporting terminal program and choose the option to select an XPR
  76. library. This usually takes place through a file requester. Direct
  77. this to LIBS: (if it isn't there already) and select the
  78. XPRBPlus.library. That should be it. If you have any problems,
  79. please read your comms program documentation on selecting an
  80. external protocol.
  81.  
  82.  
  83. 5. Options
  84. ==========
  85.  
  86. Once the library is installed there are a number of configurable
  87. options. Select the comms program command for changing transfers
  88. options and a number of gadgets should appear showing the
  89. following:
  90.             Text conversion             (Default N)
  91.             Overwrite Mode              (Default N)
  92.             Buffer size                 (Default 16)
  93.             Auto initiate               (Default Y)
  94.             Delete after send           (Default N)
  95.             Keep partial files          (Default Y)
  96.             Attempt resume              (Default Y)
  97.  
  98. The actual format of the display will change from one comm program
  99. to another, with YES/NO, or ON/OFF being displayed.
  100.  
  101. Text conversion
  102. ---------------
  103.  
  104. If this is set to YES, and the file to be uploaded or downloaded is
  105. an ASCII file, the library will carry out end of line CR/LF
  106. conversion. If it is set to OFF, no conversion will be carried out.
  107. Please note that this option only works on ASCII files and will
  108. have no effect on binary files.
  109.  
  110. Overwrite mode
  111. --------------
  112.  
  113. This can be O, N, or S and only affects downloads where a file with
  114. the same name already exists. If set to O the original file will be
  115. overwritten. If set to N, the new file will be downloaded with the
  116. file name appended with .dup or .dupNN, where NN is a number up to
  117. 99. If 99 is reached, .dup99 will be overwritten. If set to S, the
  118. transfer will be aborted.
  119.  
  120. Buffer size
  121. -----------
  122.  
  123. This sets the buffer size for disk read/writes and is in multiples
  124. of 1K. If set to zero, no buffering is used.
  125.  
  126. Auto initiate
  127. -------------
  128.  
  129. This setting affects whether transfers can be initiated by the
  130. Compuserve Host alone or whether they need to be initiated by the
  131. user through the XProtocolSend and XProtocolReceive functions. If
  132.  
  133. set to OFF, the comms program "Receive" and "Send" commands must be
  134. used.
  135.  
  136. Delete after sending
  137. --------------------
  138.  
  139. If enabled, after a successful upload the local copy of the file
  140. will be deleted. If disabled, the file will be retained.
  141.  
  142. Keep partial files
  143. ------------------
  144.  
  145. If a partial file is transmitted and this option is enabled, the
  146. file will be retained. It will then be possible to attempt to
  147. resume the transfer later. If is is disabled the partial file will
  148. be deleted. The 'Attempt resume' option also forces partial files
  149. to be retained if it is enabled.
  150.  
  151. Attempt Resume
  152. --------------
  153.  
  154. If this is enabled and a download is attempted where a file of the
  155. same name already exists, the library will first try to resume
  156. downloading the remainder of the file. The library will build a
  157. check value for the local file and will send this to the Host
  158. computer along with details of the local file's size. The Host then
  159. compares this check value to its version of the file based on the
  160. length reported by the library. If the check value matches the Host
  161. assumes that the local file is part of the file to be downloaded
  162. and will then download the remainder which the library will append
  163. to the local file. If the check value does not match the Host will
  164. download the entire file based on the setting of the Overwrite mode
  165. above. Enabling this option also temporarily disables the deletion
  166. of partial files. If a download is resumed the file transfer
  167. display will show data transfer rates and expected download times
  168. for the remainder of the file only, to avoid giving unrealistic
  169. estimates. When checking partial ASCII files, the library tries to
  170. make allowances for CR/LF conversions but it is possible to confuse
  171. this if the 'Text conversion' option is changed before the resume
  172. is attempted.
  173.  
  174. Important
  175. ---------
  176.  
  177. The "Delete after sending" and "Keep partial files" options require
  178. that the comms program implements the xpr_unlink function. Without
  179. this the library cannot delete files.
  180.  
  181.  
  182. 6. Serial Port Settings
  183. =======================
  184.  
  185. I know a lot of grief has been caused by the fact that the
  186. Compuserve documentation states that serial settings of 7 Bits,
  187. Even Parity should be used except for the Apple Mac. When I tried
  188. this originally everything appeared to work OK until I attempted to
  189. transfer files. All the transfers failed, no matter what program I
  190. was using. Only when 8 Bits, No Parity was set did the transfers
  191. work. With most comms programs this means that the "Strip 8th bit"
  192. option has to be set in order to prevent garbage appearing on the
  193. screen. I am sorry to say that with this library it's still the
  194. case that 8N should be set. Although the library does attempt to
  195. set the serial device properly during transfers itself, either my
  196. code does not work or the comms programs I have tested it with do
  197. not support the function properly. If you have problems, please
  198. make sure that the settings are 8 Bits, No Parity. If you do get
  199. the library to work with 7 Bits, Even Parity, please let me know
  200. which program you are using!
  201.  
  202. Version 1.1. Note: I have changed the serial setting code again,
  203. still to no avail. Is it actually impossible to change the settings
  204. "on the fly"?
  205.  
  206.  
  207. 7. Receiving Files
  208. ==================
  209.  
  210. Since all file transfers are initiated by the Host (ie. Compuserve)
  211. the appropriate command e.g. DOW or DOWNLOAD will need to be sent.
  212. This can be done at the appropriate Compuserve menu prompt. After
  213. the file name has been entered the Host should then initiate the
  214. transfer and the file transfer window will appear. The library
  215. recognises abort requests if your comms program supports them. As a
  216. short cut the library can send the download command itself if the
  217. comms program uses the XProtocolReceive function. This is usually
  218. called by selecting the "Receive" menu option of the comms program.
  219. This will cause the comms program to ask for a filename and once
  220. this has been entered the library to send the string "dow/proto:b+"
  221. followed by the filename to the Host. If 'Auto initiate is set to
  222. off this is the only way to initiate a download. Provided it is
  223. appropriate to the context the download should now be activated.
  224.  
  225.  
  226. 8. Sending Files
  227. ================
  228.  
  229. This is very similar to receiving files, except that the Compuserve
  230. menu command is different! You should use UPLOAD or UPL, or
  231. activate the XProtocolSend function (usually through a menu "Send"
  232. command) if your comms program supports it which will cause a
  233. filename requester to appear before sending the command sequence.
  234. Once the Host has initiated the transfer the file transfer window
  235. will again appear.
  236.  
  237.  
  238. 9. Performance
  239. ==============
  240.  
  241. The library runs roughly 3% slower than xprquickb. At present I am
  242. afraid that is the price of the file size display. The bulk of this
  243. difference is during the first 10 to 15 seconds of the transfer and
  244. I will be looking into it to see if improvements can be made.
  245.  
  246.  
  247. 10. Revision History
  248. ====================
  249.  
  250. Version 1.0.
  251.  
  252. Initial release implementing the 'File Information' Facility.
  253.  
  254. Version 1.1.
  255.  
  256. Download Resume implemented.
  257.  
  258. Incorrect freeing of memory bug (spotted by Mungwall) cured.
  259.  
  260. Use of an invalid file pointer (if a second download was attempted)
  261. cured. Also shown up by Mungwall.
  262.  
  263.  
  264. 11. The Future
  265. ==============
  266.  
  267. In the original release I wrote that I would first try to improve
  268. the performance of the library. Due to initial comments I received
  269. I decided instead to concentrate on implementing 'Download Resume'.
  270. I have pared down the source code as well in some places, but
  271. although this has reduced the size of the library (allowing for the
  272. addition of Download Resume) it has not noticeably improved
  273. performance. I will keep trying!
  274.  
  275. I will also continue to check if the problems detailed in Section
  276. 12 can be ironed out. I will add options to allow the user to
  277. control aspects of the transfer such as the number of Send Ahead
  278. buffers and the Quoting Level. I will also look further into the
  279. serial setting functions.
  280.  
  281.  
  282. 12. Bugs
  283. ========
  284.  
  285. The library has been tested with Term 2.1 by Olaf Barthel, VLT
  286. version 5.517 by Willy Langeveld and Backtalk by 1.51 by Steve
  287. Ahlstrom and Don Curtis. The only problems I have experienced so
  288. far are that the command sent by XProtocolReceive is not always
  289. successful and aborts during file transfers are not always
  290. acknowledged. I will be looking further at these as well.
  291.  
  292. I have not had chance to test the XProtocolSend function to any
  293. extent. I would be interested to hear how successful it is.
  294.  
  295. In case of bugs, please read Section 2 again and then report them
  296. to me on:
  297.  
  298.             Compuserve      ID 100021,2621
  299.             CIX (UK)        ID tfinney
  300.  
  301. If you have any comments, please let me know.
  302.  
  303.  
  304. 13. And Finally.....
  305. ====================
  306.  
  307. ....I hope you find the library useful!
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.